<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Designing Twisted Applications</title>

</head>

<body>

<h1>Designing Twisted Applications</h1>

<h2>Goals</h2>

<p>This document describes how a good Twisted application is structured. It
should be useful for beginning Twisted developers who want to structure their
code in a clean, maintainable way that reflects current best practices.</p>

<p>Readers will want to be familiar with <a href="async.xhtml">asynchonous
programming using Deferreds</a> and with writing <a
href="servers.xhtml">servers</a> and <a href="clients.xhtml">clients</a> using
Twisted.</p>

<h2>Example of a modular design: TwistedQuotes</h2>

<p><code>TwistedQuotes</code> is a very simple plugin which is a great
demonstration of
Twisted's power.  It will export a small kernel of functionality -- Quote of
the Day -- which can be accessed through every interface that Twisted supports:
web pages, e-mail, instant messaging, a specific Quote of the Day protocol, and
more.</p>

<h3>Set up the project directory</h3>

<p>See the description of <a href="quotes.xhtml">setting up the TwistedQuotes
example</a>.</p>

<h3>A Look at the Heart of the Application</h3>

<a href="listings/TwistedQuotes/quoters.py" class="py-listing">Twisted Quotes
Central Abstraction</a>

<p>This code listing shows us what the Twisted Quotes system is all about.  The
code doesn't have any way of talking to the outside world, but it provides a
library which is a clear and uncluttered abstraction: <q>give me the quote of
the day</q>. </p>

<p>Note that this module does not import any Twisted functionality at all!  The
reason for doing things this way is integration.  If your <q>business
objects</q> are not stuck to your user interface, you can make a module that
can integrate those objects with different protocols, GUIs, and file formats.
Having such classes provides a way to decouple your components from each other,
by allowing each to be used independently.</p>

<p>In this manner, Twisted itself has minimal impact on the logic of your
program.  Although the Twisted <q>dot products</q> are highly interoperable,
they
also follow this approach.  You can use them independently because they are not
stuck to each other.  They communicate in well-defined ways, and only when that
communication provides some additional feature.  Thus, you can use <code
class="API">twisted.web</code> with <code
class="API">twisted.enterprise</code>, but neither requires the other, because
they are integrated around the concept of <a
href="defer.xhtml">Deferreds</a>.</p>

<p>Your Twisted applications should follow this style as much as possible.
Have (at least) one module which implements your specific functionality,
independent of any user-interface code.  </p>

<p>Next, we're going to need to associate this abstract logic with some way of
displaying it to the user.  We'll do this by writing a Twisted server protocol,
which will respond to the clients that connect to it by sending a quote to the
client and then closing the connection.  Note: don't get too focused on the
details of this -- different ways to interface with the user are 90% of what
Twisted does, and there are lots of documents describing the different ways to
do it.</p>

<a href="listings/TwistedQuotes/quoteproto.py" class="py-listing">Twisted
Quotes Protocol Implementation</a>

<p>This is a very straightforward <code>Protocol</code> implementation, and the
pattern described above is repeated here.  The Protocol contains essentially no
logic of its own, just enough to tie together an object which can generate
quotes (a <code class="python">Quoter</code>) and an object which can relay
bytes to a TCP connection (a <code class="python">Transport</code>).  When a
client connects to this server, a <code class="python">QOTD</code> instance is
created, and its <code class="python">connectionMade</code> method is called.
</p>

<p> The <code class="python">QOTDFactory</code>'s role is to specify to the
Twisted framework how to create a <code class="python">Protocol</code> instance
that will handle the connection.  Twisted will not instantiate a <code
class="python">QOTDFactory</code>; you will do that yourself later, in the
<code class="shell">mktap</code> plug-in below.
</p>

<p>Note: you can read more specifics of <code class="python">Protocol</code> and
<code class="python">Factory</code> in the <a href="servers.xhtml">Writing
Servers</a> HOWTO.</p>

<p>Once we have an abstraction -- a <code>Quoter</code> -- and we have a
mechanism to connect it to the network -- the <code>QOTD</code> protocol -- the
next thing to do is to put the last link in the chain of functionality between
abstraction and user.  This last link will allow a user to choose a
<code>Quoter</code> and configure the protocol. Writing this configuration is
covered in the <a href="application.xhtml">Application HOWTO</a>.</p>

</body>

</html>
